Module Map

Layer-level ownership map for the workspace crates and the agentty application layers.

This guide maps the workspace crates and the agentty application layers to their responsibilities so contributors can quickly choose the correct module when implementing changes.

For file-level detail, read the module docstrings directly.

Workspace Crates🔗

Crate	Responsibility
`ag-clipboard`	Host clipboard reads
`ag-contracts`	Transport-independent execution types and interfaces
`ag-runtime`	Adapter composition and dispatch
`ag-scheduler`	Shared session admission
`ag-worker`	Scheduling, cancellation, heartbeats, recovery, execution policy
`ag-agent`	CLI, app-server, and native harness adapters; policy enforcement
`ag-forge`	GitHub/GitLab review requests and comments
`ag-git`	Worktrees, captured diff parsing, sync, rebase, merge
`ag-harness`	Native model loop, tools, durable sessions
`ag-harness-cli`	Companion harness CLI
`ag-protocol`	Response schemas, parsing, prompt envelopes
`ag-router`	Structured chat routing and provider transports
`ag-session`	Session models, policies, catalog, lifecycle API
`ag-store`	Persistence contracts, SQLite adapters, migrations
`ag-telemetry`	Content-free spans, async trace context, and opt-in OTLP export
`ag-tui-text`	Markdown, forge HTML, terminal diagrams and text layout
`agentty`	Application composition and TUI
`testty`	PTY assertions and visual recordings
`ag-xtask`	Workspace maintenance checks

All crates live under crates/. See ag-harness Design for its component contracts.

Application Layers (`crates/agentty/src/`)🔗

Layer	Owns
`main.rs` / `lib.rs`	Bootstrap and composition
`app/`	Workflows, state transitions, event reduction, service adapters
`domain/`	Pure Agentty entities and interaction policies
`infra/`	External integrations behind injectable traits
`runtime/`	Terminal lifecycle, event loop, input dispatch
`presentation/`	Shared interaction, selection, editor, and viewport state
`ui/`	Snapshot projection, layout, and rendering

Layer Rules🔗

Keep workflow changes and shared command admission in app/, with external effects behind infra/ traits. The session command gateway owns admission. A pure message planner selects existing workflows from submission intent and session state; the worker owns execution ordering and settlement.
Keep frontend-neutral session and task models in ag-session and persistence in ag-store. Task attempts project execution state from worker-owned operations; task completion is explicit outcome acceptance.
Runtime converts presentation state into typed app requests and applies returned navigation effects. app/ does not import runtime handlers or mutate AppMode.
App::view_snapshot() supplies an immutable frontend view. UI projection cannot access concrete application services; runtime owns render caches and table viewports.
Resolve the injected clock once per frame. Persist activity timestamps explicitly and apply the clock's UTC offset when grouping events, avoiding host-timezone dependence.
Share semantic interaction calculations in domain/ or presentation/; keep these independent of Ratatui rendering.
Keep paired module.rs routers free of implementation details.

For example, resource accounting puts host sampling in infra/, scheduling and cache invalidation in app/, totals in domain/, and display formatting in ui/.

See Testability Boundaries for external ports and Change Recipes for contribution paths.

Worker-owned model execution🔗

Application workflows submit session turns through SessionRunClient and isolated utilities through RunClient. Only ag-worker depends on ag-runtime; only ag-runtime depends on ag-agent; only ag-agent launches agent CLIs. Shared execution contracts live in ag-contracts. The worker owns runtime lifecycle and cancellation; applications configure workers rather than construct adapters.

See Execution for the execution contract.